home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 March / macformat-022.iso / Shareware City / Utilities / Cron ƒ / cron docs.txt < prev    next >
Encoding:
Text File  |  1992-06-21  |  9.8 KB  |  291 lines  |  [TEXT/R*ch]
  1.  
  2.  
  3.  
  4.     CRON
  5.     ——————————————————————————————————————————————————————————————
  6.     
  7.     
  8.     NAME
  9.         
  10.         cron - clock daemon
  11.     
  12.     
  13.     DESCRIPTION
  14.         
  15.         The cron daemon executes commands at specified dates and
  16.         times according to the instructions in the crontab file.
  17.         Since cron never exits, it should only be executed once.
  18.         This is best done by placing an alias to cron in the 
  19.         System 7 "Startup Items" folder.  Cron will then be exec-
  20.         uted automatically during system startup.
  21.         
  22.         The crontab file consists of lines of seven fields each.
  23.         The fields are separated by spaces or tabs.    The first five
  24.         fields are integer patterns that specify:
  25.         
  26.         o    Minute (0-59)
  27.         o    Hour (0-23)
  28.         o    Day of the month (1-31)
  29.         o    Month of the year (1-12)
  30.         o    Day of the week (1-7, with 1=Monday)
  31.         
  32.         Each pattern can contain:
  33.         
  34.         o    A number in the range above.
  35.         o    Two numbers separated by a minus (-) sign means an
  36.             inclusive range.  The final element of the range can now
  37.             be an asterisk (*), which will represent the largest
  38.             permissible value in any given field.  Support for an 
  39.             asterisk here is non-standard, and not part of the UNIX
  40.             cron specification.
  41.         o    A list of numbers separated by commas means any of the
  42.             numbers.
  43.         o    An asterisk (*) means all legal values.
  44.         
  45.         The sixth field is a user name. This is required for compat-
  46.         ibility, but is not currently used. Supply a dummy value in
  47.         this field.
  48.         
  49.         The seventh field consists of all text on the line after the
  50.         sixth field, including tabs and spaces. This field is the
  51.         command that is executed at the specified times. If the 
  52.         seventh field begins with "-b", the command that follows will 
  53.         be executed in the background.  Otherwise, commands are 
  54.         initially launched into the forground.
  55.         
  56.         Incorrectly constructed lines are ignored. No errors are 
  57.         reported to the user.
  58.         
  59.         The crontab file is examined for changes by cron every minute, 
  60.         on the minute.
  61.         
  62.         Ultimately, cron should be setup as a faceless background task,
  63.         but for the moment, it still has a face, so it can be seen in 
  64.         and selected from System 7's application menu.  When cron is in
  65.         the foreground, hitting (almost) any key on the keyboard will 
  66.         cause it to quit.
  67.         
  68.         
  69.     EXTENSIONS TO THE CRONTAB FORMAT
  70.         
  71.         This version of cron for the Mac adds some unique extensions to
  72.         the crontab format in order to allow scheduling on the basis of 
  73.         things other than just time and date.  (Obviously, these are 
  74.         non-standard, but they can be useful.)
  75.         
  76.         These extensions are added to the beginning of valid lines in 
  77.         the crontab file.  They begin with a word specifying the type of
  78.         case they represent, continue with a case-specific number of 
  79.         parameters, and conclude with a colon (:).  Following the colon
  80.         should be a normal, 7 field crontab line as detailed in the 
  81.         preceding section of this document.
  82.         
  83.         Example:  
  84.             
  85.             idle 4-* : * * * * * nobody -b beep
  86.         
  87.         The example above begins with the word specifying the case 
  88.         ("idle"), includes a numeric parameter ("4-*"), terminates the
  89.         special case portion of the line with a colon (:), and then
  90.         goes on with a perfectly normal crontab line which happens to
  91.         invoke the "beep" command in the background.
  92.         
  93.         Note that all the numeric values discussed below can be a 
  94.         single value, a range of values, a list of values, or an 
  95.         asterisk (*) representing all values.
  96.         
  97.         Also, remember that cron still executes commands only once a 
  98.         minute, on the minute.
  99.         
  100.         startup
  101.             
  102.             Schedules execution of a command relative to the time at
  103.             which the cron application is launched.
  104.             
  105.             Format:  startup N : (normal crontab line)
  106.             
  107.             N is the number of minutes after startup at which the 
  108.             command should be executed.
  109.             
  110.         idle
  111.             
  112.             Schedules execution of a command relative to the length of
  113.             time the Mac has been idle, where "idle" means that the 
  114.             mouse has not moved and the keyboard has not been used.
  115.             Perfect detection of keyboard use is not possible from an
  116.             application, so don't be surprised if this case isn't 
  117.             always handled perfectly, particularly with small delay
  118.             values. 
  119.             
  120.             Format:  idle N : (normal crontab line)
  121.             
  122.             N is the number of minutes after the Mac goes idle at which
  123.             the command should be executed.
  124.             
  125.         idlescreen
  126.             
  127.             Works just like the "idle" case, but is also sensitive to
  128.             the corner (if any) of the main screen in which the mouse
  129.             is located.  This is perfect for writing your own screen 
  130.             savers.
  131.             
  132.             Format:  idlescreen N A D : (normal crontab line)
  133.             
  134.             N is the number of minutes after the Mac goes idle at which
  135.             the command should be executed.
  136.             
  137.             A is the number of the main screen corner which should 
  138.             cause the command to be executed.  (See diagram below.)
  139.             
  140.             D is the number of the main screen corner which should
  141.             prevent the command from being executed.  (See diagram
  142.             below.)
  143.             
  144.                 Screen Corner Numbers:
  145.                 
  146.                     1---------2        0 -- No corner.
  147.                     |         |        1 -- Upper-left corner.
  148.                     |    0    |        2 -- Upper-right corner.
  149.                     |         |        3 -- Lower-left corner.
  150.                     3---------4        4 -- Lower-right corner.
  151.                     
  152.                 Screen corners are 32x32 squares, so positioning the 
  153.                 mouse in them is no challenge.
  154.             
  155.         busy
  156.             
  157.             Schedules execution of a command relative to the length of
  158.             time the Mac has been busy, where "busy" means that the 
  159.             mouse has been moved and/or the keyboard is in use.  (The
  160.             same caveats that apply to the idle command also apply
  161.             here.)
  162.             
  163.             Format:  busy N : (normal crontab line)
  164.             
  165.             N is the number of minutes after the Mac becomes busy at 
  166.             which the command should be executed.
  167.         
  168.         
  169.     DEBUGGING FEATURES (POTENTIALLY USEFUL)
  170.         
  171.         With cron in the foreground the following keys do something 
  172.         other than forcing cron quit.  They just might be useful to
  173.         you.
  174.         
  175.         d    Calls DebugStr() to get you into MacsBug in cron's
  176.             context.
  177.             
  178.         s    Translates the tokenized, memory-resident version of the
  179.             crontab file which cron is currently using into ASCII
  180.             and writes it out to a file named "crontab export" in 
  181.             the same directory as the cron application.  This is 
  182.             handy if you're trying to track down incorrectly con-
  183.             structed (and therefore ignored) lines in the crontab 
  184.             file.
  185.             
  186.         Another feature which aids debugging is the "cron log" file
  187.         which records what commands are executed and when.  It does
  188.         not record whether or not the commands worked, just whether
  189.         or not they were invoked.
  190.  
  191.  
  192.     NOTES
  193.         
  194.         Unlike the UNIX cron, a % character in the seventh and following
  195.         fields is not translated to a newline character.  
  196.         
  197.         Escape sequences are supported in all fields, so preceding a 
  198.         character by a backslash (\) will cause the character to be
  199.         ignored for parsing purposes.  In addition, the standard set of
  200.         escape sequences are supported:
  201.             
  202.             \a        alert (bell) character
  203.             \b        backspace
  204.             \f        formfeed
  205.             \n        newline
  206.             \r        carriage return
  207.             \t        horizontal tab
  208.             \v        vertical tab
  209.             \\        backslash
  210.             \?        question mark
  211.             \'        single quote
  212.             \"        double quote
  213.             
  214.             Hexadecimal (\xhh) and Octal (\ooo) sequences are not 
  215.             currently supported, however.
  216.         
  217.         Double quotes can be used to delimit fields.  For example, the 
  218.         file name "Captain’s Suite" is interpreted as a single field if
  219.         it is surrounded by double quotes, but as two fields ("Captain’s"
  220.         and "Suite") if the quotes are omitted.  The parsing code is not 
  221.         currently sensitive to single quotes.
  222.     
  223.     
  224.     CRON AS AN APPLICATION
  225.         
  226.         Ultimately, cron will be a faceless background program which 
  227.         won't appear in the application menu.  For development purposes, 
  228.         however, it's more convenient to allow it to show-up there.  It
  229.         still doesn't have any sort of user interface, but you can (at 
  230.         least) force it to quit by selecting it in the application menu 
  231.         and hitting any key.  Cron should quit immediately.
  232.         
  233.         No user interface helps guarantee that cron runs in the smallest
  234.         possible amount of memory.  It currently runs in 34K and will
  235.         probably work perfectly well in less.
  236.         
  237.         Any user interface that is eventually created will be a separate
  238.         program.
  239.         
  240.         
  241.     ARGUMENT PASSING
  242.         
  243.         If you are interested in writing commands for cron, read the 
  244.         following.  If not, ignore the rest of this file.
  245.         
  246.         One of the things that makes cron capable of doing useful things
  247.         is its ability to pass arguments to the programs it executes.
  248.         Since the Mac OS has virtually no provision for argument passing,
  249.         a scheme had to be invented for cron.
  250.         
  251.         Cron passes arguments to the programs it executes in a custom 
  252.         AppleEvent.  In order to get its arguments, a program must call
  253.         a routine named argcReceiver which will wait as much as one min-
  254.         ute for the appropriate AppleEvent to arrive.  If the arguments
  255.         are not received within one minute, argcReceiver calls 
  256.         ExitToShell to terminate the program.
  257.         
  258.         ArgcReceiver takes two parameters: a pointer to an argc and an 
  259.         argv variable.  The call typically looks like this:
  260.         
  261.         void main() {
  262.             int                        argc;
  263.             char                     **argv;
  264.             
  265.             argcReceiver(&argc, &argv);
  266.             
  267.         /*    Put the rest of your main procedure down here.... */
  268.             
  269.         }
  270.         
  271.         Normally, you'll call argcReceiver before your main does anything 
  272.         else.  Once you've made the call, argc and argv will be filled out
  273.         *exactly* as they would be in a normal C programming environment.  
  274.         So, apart from having to make this one procedure call at the start
  275.         of your main program in order to get at your arguments, you can use
  276.         the arguments exactly as you're accustomed to doing so in other 
  277.         environments, like UNIX.
  278.         
  279.         Note that cron provides no support for stdin, stdout, stderr or 
  280.         exit return values.  Work is underway on a separate product that
  281.         will support all this and more, however.
  282.         
  283.         The source code for argcReceiver is in the cron folder along with
  284.         the source code for argcBuilder - a collection of routines which
  285.         make it fast and painless to assemble and transmit the argument
  286.         AppleEvents to other programs.
  287.  
  288.  
  289.  
  290.  
  291.